BBS in a Box 5/BBS in a Box -Volume V (BBS in a Box) (April 1992).iso/Files/Word/Ae-An/Alpha.20.release.cpt/Alpha.2.0.rsrc/STR#_129.txt

Text File | 1990-08-24 | 26.4 KB | 1,311 lines

^        beginning of line

$        end of line

.        any character except newline

[...]    character class, can use ranges such as '0-9'

         inside classes

[^...]   negated character class

*        zero or more occurences of the previous pattern



'\' is the escape character. Regular expressions

constructed from one of the above elements can be

concatenated to other regular expressions to create larger

regular regular expressions.



EXAMPLE: A regular expression to look for the next function

         declaration might be:



              ^[^ \t#]*(.*)$



Regular expressions are very powerful, but unfortunately

my first pass is a recursive function that is rather slow

on 8MHz machines. This WILL change (I work on a

refurbished ~1984 machine, so it hurts me as much as

anyone else).





Defining and Using File Sets

=================================



File Sets are used to specify a list of files for ALPHA

to use for functions such as 'createTagsFile', and multi-

file search. File sets are defined by loading a file set

definition. The syntax for file set definitions is as

follows:



    ( fileSet <file-set-name> "<complete-path-name>"* )



For example:



(fileSet edit1

    "jpl341:Pete:Alpha.101:edit:bindings.c"

    "jpl341:Pete:Alpha.101:edit:center.c")



defines a fileset named 'edit1' which contains the files

"bindings.c" and "center.c".



Functions that use file sets operate on the "current"

fileset, which is specified by the 'fileSet' variable.

This variable can be changed by loading a new definition

for that variable, or selecting the "File Sets..." menu

item from the "Customie" menu.











Customizing ALPHA

=================================

The AlphaBits file allows you to customize ALPHA to your

tastes. There are three different types of statements in

the Alphabit file:



• Key Bindings



  Any function or loaded macro can be bound to any single

  keystroke. One way to bind a function is with a

  statement such as:



      (bind '<character>' [modifier string] funcName)



  where c is a character, 'modifier string' is a string

  containing one or more of:

      c   - command modifier

      o   - option modifier

      s   - shift modifier

      z   - control modifier

      e   - escape modifier

      x   - prefixChar modifier



  The following line binds cmd-shift-f to the function

  'forwardChar':



      (bind 'f' <cs> forwardChar)



  This form actually converts the ascii code into a US

  keycode through a hard-coded table unless the var

  'convertToCodes' is set to 'off', which foreign keyboard

  owners will want to do. A second form of binding allows

  you to bind the rest of the keys on your keyboard,

  including function keys:



(bind '\<2-digit hex key code>' [modifier string] funcName)



  The following line binds F13 to the function '

  forwardChar' on a datadesk-101 keyboard:



      (bind '\6f'  forwardChar)



  The key code for any given key can be obtained by using

  the 'keyCode' function. It is important to recognise

  that both forms are machine-dependent. The ascii chars

  are converted to key codes through lookup in a hardcoded

  table. If this was not done, the char in the quotes

  would also have to reflect the modifier keys, (i.e. the

  binding for control-a would have to have a 'control-a'

  between the single quotes instead of an 'a'). In both

  forms, the modifier string is optional. To use ALPHA

  with an original mac keyboard, uncomment the line:



      "#define OLDMAC ....."



  The loaded bindings will actually be a superset of the

  necessary mappings for the original mac keyboards, the

  extra bindings are used for a DataDesk 101 keyboard.



  Because the hardcoded key codes reflect only the US

  keyboards, another form was added which bypasses the

  keycode conversion. However, the ascii code must be

  entered in decimal. Whereas the normal binding for

  'beginningOfLine' is:



      (bind 'a' <z> beginningOfLine)



  the ascii binding will be:



      (ascii 1  <z> beginningOfLine)



  because 1 is the ascii code for control-a. The modifier

  string is optional in this form as well.



  Note that menu item command equivalents take precedence

  over bindings. Command equivalents can only be changed

  by using an external tool like 'ResEdit'.



• Setting Variables

  There are many user-definable integer variables in ALPHA.

  Variables are defined as follows:



      (set sillyVar 1)



  The values 'on' and 'off' map to '1' and '0',

  respectively, so the above example could be written:



      (set sillyVar on)



  There are also a few string variables, which are bound in

  an analogous fashion:



      (set dumString "the string")



• Macro Definition

  See Macros



• The 'User' Menu

Alpha allows the the user to build up a custom menu which

contains names of functions or macros that just HAVE to be

in the menus, as opposed to being merely callable through

the bindings. The syntax is dead simple. See the

'AlphaBits' file for an example. The following meta

characters can be embedded in the strings:



As described in the section "Creating a Menu in Your

Program", the following meta-characters may be embedded

in the data string:



   Meta-character     Usage

   --------------     -----



    ; or Return       Separates multiple items

    ^                 Followed by an icon number, adds

                      that icon to the item

    !                 Followed by a character, marks the

                      item with that character

    <                 Followed by B, I, U, O, or S, sets

                      the character style of the item

    /                 Followed by a character, associates

                      a keyboard equivalent with the item

    (                 Disables the item







ALPHA's default setup uses the command key like any other

mac application. Problems arise in ALPHA's emulation of

emacs key bindings. Emacs uses an escape key and a

control key.



For the Classic Macs, we map the escape key to the

backquote key and use the option key for the emacs command

key. Newer Macs have both an escape and a command key, so

this is not necessary. The default MacII template is set

up w/ the 'control' key for emacs command combinations,

while the classic mac template uses the option key.



Bindings, variable definitions, and macros can all be

loaded in one of three ways:



  1) The 'AlphaBits' file is always loaded at startup.

  2) The "Load Window" item of the Customize menu loads

     an entire window at once.

  3) If a selection is hilited, the above item changes to

     "Load Selection", and only the hilited text get loaded.



ALPHA supports unlimited undo and redo. This means that

every supported (everything but 'insertFile') change that

you make to your file can be undone, and then redone if

you undid :-) too far. Bear in mind that once you create

new modifications, all changes that you have undone but

not redone are lost. If this is confusing, just play with

it for a while.



Another point to bear in mind is that saving a buffer to

disk currently flushes the undo buffer. I did this because

of memory constraints, but if enough people would prefer

some other way of limiting the amount of undo information

(say, like Preditor), we can do that too.





Alpha command (ACMD) code resources can be loaded and

executed to transform the current selection. An 'ACMD'

resource is just a code resource that takes a string

pointer as an argument and returns a string pointer as

it's result. The input string is allocated w/ 'NewPtr',

and the output string must be allocated w/ NewPtr as well.

This output string could be the same block of memory that

was passed in to the ACMD, or it could be a block that the

ACMD allocated itself (say, if the ACMD wanted to return a

larger chunk of text than was passed in). In this case,

the ACMD should de-allocate the input string w/ DisposPtr

when it is no longer needed. The input string will always

be at least size 1 and is null-terminated. Carriage return

characters delimit individual lines. In summary:



  • A new pointer is allocated with size equal to the

    size of the current selection + 1.



  • The selection (if any) is copied into the new pointer.

    The string will be null-terminated w/ carriage

    returns to delimit lines.



  • The first 'ACMD' resource in the chosen file (type

    'AEXT') is loaded, and called as a 'C' function w/

    the string as it's only parameter.



  • The ACMD transforms the string, and returns it as it's

    result. Therefore, your code resource's 'main' routine

    should be declared as type 'char *', taking a single

    parater of type 'char *'.



  • The original selection is replaced with the transformed

    text.



  • The ACMD resource is released.



ACMD's that are in the 'Alpha' resource fork are added to

the ACMD menu under 'Utilities' and are callable from

macros (macros allow ACMD functions to be bound to

keystrokes). ACMDs can be executed from other files of

type 'ACMD', but are not added to the menu. To

permanently add an 'ACMD' to Alpha, use ResEdit.











Defining and Using Macros

==========================

ALPHA supports keyboard macros which record a sequence of

keystrokes to be played back later w/ the function '

executeKeyboardMacro' (this function is also in the '

Utilities' menu) or written into a buffer by selecting

'Dump Function' from the 'Utilities' menu. The dump

function prompts you for a macro name, which must consist

only of letters of the alphabet, digits, and '_'.



These macro declarations can then be edited, loaded, and

bound to keystrokes. Loading a macro or a binding is

accomplished by hiliting the text and selecting the "Load

Selection" item of the 'Customize' window. If no text is

hilited, the entire window is loaded by the same command.

Macros can be bound to keys in exactly the same manner as

functions (see above).



Macros lines can be as simple as the name of a function or

previously defined function. Macros can set variables. The

functions 'saveVars' and 'restoreVars' have been provided

to let macros leave the environment in the same state that

they found it. The keyword "type" has been provided to

enter text. One good way to learn to write macros is to

record a macro and dump it to a file. Play w/ it, change

things around, add functions, and reload it. If you want

to keep it, just put it in the 'AlphaBits' file. Several

example macros have been provided in the 'AlphaBits' file.



Macros can be of any length, but individual lines must be

less than 80 characters in length, or all hell will break

loose!



Currently there is little or no error checking done in

macros, so if you use the iteration count to execute a

macro on the next 100 lines, but there are only 20 lines

in the file, hmmm...



Several commands which prompt for input actually compile

the result of the prompt into the macro, as opposed to

again prompting every time the macro is executed. These

commands include the search and replace commands, 'ACMD'

calls, and setting named marks and clipboards. To see what

is compiled in these cases, try creating such a macro and

dumping it to a buffer.



The following are commands that can only be executed from

macros, see the distributed 'AlphaBits' file for examples

of use and syntax.



• acmd - execute named acmd, which must be in the

  resource fork of Alpha

• clipsearch - search for contents of named clipboard

• copyclip - copy selected text to named clipboard

• cutclip - cut selected text to named clipboard

• define - used to name macro

• deleteclip - delete named clipboard

• deletemark - delete named mark

• fileSet - used to define file sets

• goto - goto named mark

• mark - create named mark

• menu - used to instantiate the user menu

• replace - replace selection

• replaceFindAgain - replace and find again

• restoreVars - restore all numeric vars to saved values

• saveVars - save all numeric vars

• search - search for string, based on current flag values

• set - used to set variable contents (mirrors command that

  works outside macros as well

• type - inserts string into current window

• yankclip - yank from named clipboard







Defining and Using 'C' Tags

==========================



ALPHA supports the use of tags to find declarations of

functions. When searching for a tag, ALPHA looks for the

tag file specified by the "tagFile" string variable.

ALPHA's tag generating routines use the regular expression

in the string variable "funcExpr" to look for function

declarations. In other words, we don't parse the text. If

you declare your functions differently, you can change "

funcExpr" to suit your own style. The default expression

is the following:



  "^[^ \t#]*(.*)$""



Note that not only can you customize this to your style

of 'C' declarations, you could also use it to generate

tags for other languages. The only thing you need to bear

in mind is that the tag routines use the complete word

previous to the first '(' in the selected line as the

function's name. If there is no '(' in the selected line,

the last word in the line is used. Therefore, Pascal

procedures w/ or w/o parameters can be identified.



















Explanation of Variables

==========================



When variables are set:



backupFolder      • if 'useBackupFolder' is true, backup

                    files are placed in the folder specified

                    by the complete pathname in 'backupFolder'.

convertToCodes    • if non-zero, all bindings of the form

                    "bind 'c' ...." are internally converted

                    to key codes. Those w/ foreign keyboards

                    will want this turned off.

defHeight         • If 'fullScreen' set, this is default

                    height in pixels.

defWidth          • If 'fullScreen' set, this is default

                    width in pixels.

elecLBrace        • Electric 'C' left brace on.

elecRBrace        • Electric 'C' right brace on.

electricSemi      • Electric 'C' semicolon on.

fillColumn        • Number of columns use as limit for

                    "fill" functions. See 'leftFillColumn'

fontSize          • Default size of fonts used to display

                    files.

forward           • set when searching forward. The 'findFile'

                    dialog always resets this before

                    displaying.

fullNames         • Windows display pathnames instead of

                    mere file names.

fullScreen        • If on, all windows are start in the

                    same place, and have the dimension

                    specified by 'defHeight' and 'defWidth'.

funcExpr          • Set to the regular expression that

                    ALPHA uses to find function declarations.

ignoreCase        • Search is case-insensitive.

includePath       • A list of the path-names of the

                    directories to search for include files,

                    separated by semi-colons, such as:

                      "Disk:C:edit;Disk:C:THINK C:include;"

                    The current directory can be included

                    by using consecutive semi-colons as:

                      "Disk:C:edit;Disk:C:THINK C:include;;"

indentOnCR        • Auto-indent on carriage return.

keepBackup        • Keeps old version in <file>.BAK

leftFillColumn    • Number of blanks at left of lines.

matchWords        • Match words on searches.

noRemapOption     • When set, does not overlay system

                    resource w/ one that does not have

                    "dead keys". If TRUE, some option

                    sequences are not usable. Owners of

                    foreign keyboard will want this turned

                    on.

numWinsToTile     • specifies the number of windows tile

                    commands should affect.

regExpr           • flag set if searchAgain should look

                    for a regular expression

startWithNew      • When one, ALPHA comes up w/ new

                    buffer. When 0, ALPHA comes up w/

                    a prompt for a file. When 2, ALPHA

                    comes up w/ nothing.

suppressHeader    • Suppress header on printed pages.

tabSize           • Default number of characters per tab.

tagFile           • complete path-name of tag file

useBackupFolder   • if true, backup files are placed in

                    the folder specified by 'backupFolder'

wordWrap          • if true, lines exceeding 'fillColumn'

                    in length are automatically wrapped

                    during normal text insertion (typing)







Function Summary

==========================



Many of the commands manipulate 'regions'. Regions come

from emacs and are used to refer to all of the text

between the current 'mark', and the insertion point. The

current 'mark' is set by the 'setMark' command, or

commands such as 'beginningOfBuffer' or 'endOfBuffer'.

You will always know when the mark is set because the

status line will say 'Mark set'. All of the region

commands also work on blocks of text that are currently

selected.



Several functions deal with 'C' functions. As stated

above, 'C' functions are detected not through parsing, but

through pattern-matching the string "^[^ \t#]*(.*)$"".



• abortEm - aborts whatever is currently happening

• backwardCharSelect - extends selection one char back

• backwardChar - moves insertion one char back

• backwardDeleteWord - deletes previous work

• backwardWord - moves insertion one char back

• balance - selects smallest set of parens, braces, or

  brackets that encloses the current selection

• beginningBufferSelect - extend selection to the

  beginning of the buffer

• beginningLineSelect - extend selection to the

  beginning of the line

• beginningOfBuffer - move insertion to the beginning

  of the buffer

• beginningOfLine - move insertion to the beginning of

  the line

• capitalizeRegion - capitalize all words in selected

  region

• capitalizeWord - capitalize word

• carriageReturn - insert carriage return, indent new

  line if the variable 'indendOnCR' is set to 'on'

• closeAll - close all windows

• copy - copy region

• copyClip - copy to named clipboard

• createTagFile - searches all files in current file set

  and saves the locations of any function declarations in

  a file called 'cTAGS'.

• currentPosition - displays number of lines and current

  position (row and col) in the status line.

• cut - deletes and saves region

• cutClip - cut to named clipboard

• deleteChar - delete char AFTER cursor

• deleteWord - delete word after cursor

• doNew - opens an untitled window

• doSave - saves current window

• doElectricSemi - insert semicolon, and if '

  electricSemi' is set, insert a carriage return and

  indent the new line

• doTab - insert a tab

• doQuit - quits ALPHA

• doZoom - zooms the current window

• downcaseRegion - changes all uppercase letters to

  lowercase in current region

• downcaseWord - changes all uppercase letters to

  lowercase in current word

• dumpMacro - prompts the user to name the current

  keyboard macro and then dumps a definition of the macro

  into the current buffer

• electricLeftBrace - if 'electricLBrace' is set, make

  sure that the brace is on a new line, open a further

  line and indent to the "proper" level.

• electricRightBrace - insert a right brace on the

  correct line and open a new line

• endBufferSelect - extend selection to the end of the

  buffer

• endLineSelect - extend selection to the end of the line

• endKeyboardMacro - stop recording keyboard macro

• endOfBuffer - move insertion to the end of the buffer

• endOfLine - move insertion to the end of the line

• exchangePointAndmark - exchange the current 'mark'

  w/ the current insertion point

• executeKeyboardMacro - execute the current keyboard

  macro

• fileInfo - prompts for a file, and displays type,

  creator, sizes of both data and resource forks, last

  modification time, and creation time

• fileRemove - prompts for a file, and removes it

• fileStats - displays chars, words, and lines for current

  window

• fillParagraph - inserts/deletes lines and moves text

  in the current paragraph in order for all text to fit

  between the columns 'leftFillColumn' and 'fillColumn'. A

  paragraph is here defined as any block of text delimited

  by white-space lines

• fillRegion - as above for current region

• findTag - prompt user for a function name and attempt

  to use the file 'cTAGS' to locate the function's

  definition

• findFile - open a new file

• forwardCharSelect - extend selection one character

  forward

• forwardChar - move insertion one character forward

• forwardWord - move insertion one word forward

• freeMem - give a rough approximation of the current

  memory reserves of ALPHA

• getAscii - displays the ASCII code for character at

  current insertion ponit

• getHelp - display help dialog

• getPathName - present the user w/ a SFGetFIle dialog

  and paste the complete path-name of the chosen file into

  the current window

• gotoLine - go to a line number

• gotoMark - goto named mark, use 'mark' in macros.

• includeFile - expand the current selection to include

  the suffix and use the var 'includePath' to try to

  find the include file.

• insertAscii - prompts for an ASCII code and inserts into

  text.

• insertFile - prompts for a file name and inserts the

  corresponding file into the current window. Not

  undoable.

• insertToTop - make the line that the insertion point

  is on the first line shown, and display the current line

  number along w/ the total number of lines in the file

• iterationCount - allows actions to be repeated many

  times. "option-u 44 =" inserts 44 '='s into the current

  window. Also can be used to execute any function or

  macro (including the keyboard macro) many times.

• keyAscii - insert the ascii representation (in decimal)

  of the keydown event, plus a modifier string, if

  necessary.

• keyCode - insert the key code along w/ a string

  representing and modifiers into the current window. This

  function can be used to create bindings in the '

  alphaBits' file.

• killLine - kill text from insertion point to the end

  of the line. If the line has no text, delete the line

  and move succeeding lines up one.

• killWindow - kill current window

• loadFile - loads hilited text, or entire window if

  nothing is hilited. 'load'ing means that whatever

  bindings or macro definitions are present in the loaded

  text take effect

• markHilite - This is the 'Hilite' from the 'Edit' menu.

  If there is a currently hilited selection, the selection

  is unhilited, leaving the mark and the insertion point

  around the old selection. If there is not a selection,

  the region between the insertion point and the mark is

  selected.

• matchBrace - moves the insertion point to the

  character that matches the character after the current

  insertion point

• nextLineSelect - extend selection to the next line

• nextFunc - select first line of next 'C' function

  declaration

• nextLine - move insertion point to next line

• nextWindow - select next window

• openLine - insert a new line following the current

  one and move the insertion point to it

• pageBack - display previous screenful

• pageForward - display next screenful

• paste - insert the last chunk of text created by 'cut'

  or 'copy'

• pasteClip - paste to named clipboard

• prefixChar - used to further modify the next keystroke

  combination, in the same manner as using the shift key

  in the next keystroke

• prevLineSelect - extend selection to the previous line

• prevFunc - hilite first line of previous 'C' function

  declaration

• prevWindow - select previous window

• previousLine - move insertion point to the previous

  line

• quickSort - sort the lines in the current region

• redo - redo the next action that has been undone but

  not redone

• repeatSearchBackward - repeat search backward

• repeatSearchForward - repeat search forward

• restoreVars - restore variables to saved state,

  see 'saveVars'

• revert - revert the file to it's last saved version

• saveVars - save variable state, see 'restoreVars'

• scrollDownLine - same action as that which occurs when

  the down arrow in the vertical scrollbar is selected

• scrollUpLine - same action as that which occurs when

  the up arrow in the vertical scrollbar is selected

• searchEnter - use current selection for future searches

• searchRall - replace all futher occurances in the

  current file

• searchReplace - replace the current selection

• searchRfa - replace the current selection and find

  next occurance

• set - macro-only func to set var values, see examples

• setMark - set the current mark to the insertion point

• setNamedMark - set a named mark in a file, use 'mark'

  in macros

• shiftRegionLeft - shifts the current region left a tab

• shiftRegionRight - shift the current region right a tab

• startEscape - used to further modify the next

  keystroke combination, in the same manner as using the

  shift key in the next keystroke

• startKeyboardMacro - start recording keyboard macro

• tileFull - make all windows "full screen"

• tileHor - tile the windows horizontally

• tileOrder - offset each window from the previous by a

  set horizontal and vertical amount

• tileVert - tile the windows vertically

• undo - undo the last action that has not been undone

• upcaseRegion - convert all lowercase letters to

  uppercase in the current region

• upcaseWord - convert all lowercase letters to

  uppercase in the current word

• winSearch - brings up search and replace dialog

• yank - insert the last piece of text that has been

  'cut', 'copy'd, or deleted in any way. Note that 'yank'

  is different from 'paste' in that 'paste' doesn't know

  about text that was merely deleted. Ordinarily, "the

  last deleted text" refers to text that was deleted in

  one keystroke, but consecutive 'killLines' have their

  text glommed together for this purpose.